Apple Developer Connection Student Program

home *** CD-ROM | disk | FTP | other *** search

/ Apple Developer Connection Student Program / ADC Tools Sampler CD Disk 3 1999.iso / Apple Development Tools / MacsBug 6.5.4a6.sit / MacsBug 6.5.4a6 / MacsBug 6.5.4a6 Read Me < prev next >

Wrap

Text File | 1998-09-22 | 16KB | 382 lines

 About MacsBug 6.5.4a6 9/14/98 INSTALLATION INSTRUCTIONS • MacsBug includes a number of folders. The contents of each is as follows: “into System Folder” - This contains MacsBug itself. To install, place the “MacsBug” file into your System folder and restart your machine. “into MacsBug Preferences folder” - This contains optional debugger commands (“dcmds”). There are currently two dcmds in this folder; Leaks and PageFaults. Leaks is no longer included within MacsBug because it patches a number of Memory Manager traps with 68K code, potentially slowing down the system. PageFaults isn’t installed because it patches the virtual memory system, also potentially slowing down some operations. To install either dcmd, copy the appropriate file into your “MacsBug Preferences” folder, which is located in your “Preferences” folder. “into Debugger Prefs file” - This contains the standard U.S. 'KCHR' keyboard translation resource. It is needed when using MacsBug to debug on a system that is using a non-U.S. keyboard layout (MacsBug requires U.S. keyboard translation). To install, copy the 'KCHR' resource from this file into your “Debugger Prefs” file using ResEdit, or rename the file to “Debugger Prefs”. The file must be located in the System folder. “Building dcmds” - This contains sample C and Pascal source for a variety of dcmds, as well as all headers and libraries necessary to build dcmds within the MPW and Metrowerks CodeWarrior environments. • The set of dcmds that was previously distributed in the optional file “PowerPC dmcds” has been merged into MacsBug itself. When installing MacsBug, you should make sure to remove this file from your “MacsBug Preferences” folder. • When MacsBug is first entered, it displays a message if it has encountered dcmds that have the same name. If you see this message, you should examine all of your preference files and remove any duplicates. MacsBug does not guarantee which dcmd is used when a name collision occurs, so you may be accidentally using an old dcmd. A-TRAPS • You can now step into the KeyTranslate trap if you so desire. You used to step into MacsBug’s patch (which is only installed when MacsBug is active), but you wouldn’t know that because it would lock up the machine before you got there. BREAKPOINTS • When setting a breakpoint in a file-mapped file, we no longer leave the 4K page containing the breakpoint writeable. DISASSEMBLY • When disassembling a 68K JSR (An) or JMP (An) at the current PC, and the address register used by the instruction has a bad value, we no longer explode trying to show the PC window. We now display something like this if we can’t read from the destination address: +0000 015D5B0 *JSR (A0)=<Bad Destination Address> | 4E90 • When disassembling a cross-TOC PowerPC call, and the library we’re calling into has as its first exported symbol a re-export from another library, we no longer use the wrong value for the TOC register. This prevents the embedded symbol searching code from crashing. • When scanning through exported symbols from a CFM container, we now skip past re- exported unresolved weak imports (whew!). This fixes a problem where we’d not show any of the exported symbols from a certain glue library. • When symbols are off, we still do macro replacement so names will show up in PowerPC low memory accessors. FILLING MEMORY • Enhanced FILL to support byte, words, longs, and strings, and removed the restriction that the number of bytes be a multiple of four. FONTOLOGY • Most control characters are no longer drawn. The font was expanded in 6.5.4a5, but this made for a cluttered display, which made browsing for ASCII in memory dumps more difficult. HEAP COMMANDS • Amazingly, “HC ALL” (Heap Check) didn’t. Under Modern Memory Manager systems it failed to check most application heaps. • When running under the Modern Memory Manager, we now check the free block list for consistency. • Fixed a bug where the master pointer free list wasn’t being checked if running under the Modern Memory Manager. • “HX” (Heap Exchange) now supports two additional methods to select a target application heap. You can now specify the heap by creator as in “HX 'MACS'”, or by using the application name as in “HX "Finder"”. MOUSE CONTROL • When the history area sees a click on a word, it now cleans it up a bit before inserting it into the command line. Specifically, we remove “0x” or '$' from the beginning of a 2-, 4-, or 8-digit hex number, and remove trailing commas (','). • When resizing the PC window, the minimum height of the PC area is now two lines. • You can now disable MacsBug’s use of the mouse two ways. You can permanently disable it by setting the “Don’t use mouse in MacsBug” bit in the 'mxpr' (MacsBug Preferences) resource in your “Debugger Prefs” file. You can also use the new “MOUSE” option to the “SET” command to turn it off at runtime. Turing the mouse off can be useful when debugging code that tracks an action while the mouse button is down. • MacsBug no longer generates spurious mouse downs when MacsBug is entered and the mouse was already down. Usually you’d notice that the history area had been clicked if you had the mouse button down and moved the mouse. MISCELLANEOUS • Added “FKEY” (Function Key) command. For example, “FKEY 3” takes a screenshot, provided the File Manager is not busy and you have a valid A5 world. • “SET SIMPLIFIED” now refreshes the PC window. • If MacsBug is entered in 68K code as a result of an exception that went unhandled in PowerPC code, we now say something useful about the event. We used to say “Spurious Interrupt or Uninitialized Interrupt Vector” which had absolutely nothing to do with what really happened. This should occur very rarely (such as when MacsBug starts speaking Esperanto and throwing furniture about). • “log?” or “log ?” now shows the status of logging. • Completely rewrote MacsBug’s keyboard input path to share identical code between MacsBug and MacsBugApp. Rewrote MacsBug’s display primitives to be more flexible for future mouse-based control. Neither of these is directly user-visible, but much code has changed, and we could have broken something. NMIs • When handling an NMI in PowerPC code, we no longer allow one to trigger while MacsBug’s nub code is active. This prevents some rare but annoying crashes with the new Watch Points implementation. POWERPC REGISTERS • Added a new command, “TV” (Total PowerPC Vector display), which shows the PowerPC AltiVec™ vector registers if they are present. • Added registers v0 through v31 to support the PowerPC vector unit. These are mostly useless right now since they are 128-bit registers, and MacsBug can only deal with 32-bit values. • Added the 601 MQ register to the PowerPC registers shown by “TD”. We knew you’d been craving it. • Disassembly now knows names for all of the supervisor registers present in the 603, 604, 604e, and 740/750 processors. REBOOTING • The “RS” (Restart) and “RB” (Reboot) commands now work again on PowerPC machines older than the Power Macintosh 9500. This was broken when we removed support for the Mac Plus in 6.5.4a3. SYMBOL LOOKUP • Finally fixed and re-enabled our symbol lookup cache. Some symbol lookups should be slightly faster, but you probably won’t notice it. • Fixed PowerPC symbol lookup to find traceback symbols correctly if we’re looking for a symbol that is not all uppercase. This was broken in 6.5.4a5. • Added a predefined symbol called “TaskLevel” that is an indication of roughly what execution context you’re currently executing in. If TaskLevel evaluates to zero, then the 68K interrupt level is zero and we’re not running VBLs, Deferred Tasks, or Secondary Interrupt Handlers. That’ll let you catch most things that run at interrupt time - even if the interrupt level is zero. Also defined is a macro to TaskLevel: TL You can use TaskLevel like this: ATB HLock TaskLevel!=0 That sets an A-Trap break on HLock if it’s made at interrupt time. The value that TaskLevel returns can also be masked: Mask with 0x00000007 to get just the 68K interrupt level. Mask with 0x00000010 to get just the “in VBL” bit. Mask with 0x00000020 to get just the “in Deferred Task” bit. Mask with 0x00000040 to get just the “in Secondary Interrupt Handler” bit. • When virtual memory is on, MacsBug can now find symbols in file-mapped application fragments when the associated heap is targeted with “HX” (Heap Exchange). • When displaying information on an address that is within a CFM fragment, we now show the base and offset into the fragment, as well as the base and offset of a section (if any). • Looking up a CFM symbol by name is now case-sensitive. We fall back to the old case- insensitive search if we don’t find exactly what you typed. • When searching for a CFM symbol, we now search the CFM context associated with the current user zone first. This makes PowerPC name lookup track the “HX”ed heap just like 68K code always has. • Optimized the search for embedded 68K symbols in a block that has few or no symbols. For a 64K block with no symbols and no LINK A6 (the worst case), we used to call one function 32,768 times. Now we’ll do it once, but you still probably won’t notice it. • When adding a ROM map symbol to our internal list, we now make sure the symbol is actually in ROM before using it. This fixes problems with some malformed ROMInfo files. • Fixed a potential heap-corruption bug when processing the ROMInfo file at startup. If there were more symbols in the file than our original guess, a failure in resizing a temporary buffer was ignored. • Added recognition of Microsoft Office 98-style cross-TOC glue. TEMPLATE BASIC TYPES • The RGNHANDLE type now allows wide-open regions to have top and left of -32,768 rather than -32,767. • Regions now show the height and width of the bounding box, as well as annotating the order of the points. • Empty regions are now shown as “[empty(0)]” if the bounding rectangle is (0,0,0,0) or just “[empty]” if the bounding rectangle is simply empty. • The heights and widths of regions and rectangles no longer show up as negative when they are merely greater than 32,767. • Added a number of basic type aliases: UInt8, SInt8, UInt16, SInt16, UInt32, and SInt32. TRANSITION VECTOR COMMANDS • Added initial support for “TVBA” (TVector Break in Application context) and “TVTA” (TVector Trace in Application context). These commands don’t work with CFM-68K, and might never. • “TVC” (TVector Clear) now allows an address of a TVector. It now treats the symbol name as case-insensitive. • When “TVD” (TVector Display) is showing the table, the output is now abortable. This is particularly useful when you’ve set breaks on all symbols in a library, and thus have a very large list. • When you create a TVector action, we now display the symbol exactly as we got it from CFM, instead of how you typed it. • When adding multiple TVector actions (TVB, TVT, etc.) to our internal table, if it fills up we now stop trying to add more actions on the first failure instead of showing an error for each action we couldn’t add. VIRTUAL MEMORY SUPPORT • Fixed two instances of improperly calling the function PageFaultFatal deep in the bowels of MacsBug’s memory accessor code. This makes stack crawls and template displays (among likely other things) work correctly at page-fault-fatal time instead of failing with “unable to access that address”. I’m a wingnut, ok? • MacsBug now understands that it can be loaded before VM is enabled, and will update it’s idea of the world if VM state changes. This is really only useful for debugging the Mac OS. WATCH POINTS • Completely rewritten. Watch Points is now a PowerPC-only feature. See the “About Watch Points 6.5.4a6” document for complete information. DCMDS AND DCMD SUPPORT • Added a sample Metrowerks CodeWarrior Pro 3 dcmd project. • Fixed a bug that caused MacsBug to crash at startup if a dcmd was an odd number of bytes in length. • Fixed a bug in the expression evaluator that could cause dcmds to loop forever waiting for input if a syntax error was detected during a call to dcmdGetNextParameter or dcmdGetNextExpression. • Cache - 3.0b2 Fixed a bug that caused a crash when a stale VCB pointer was left in a cache header. Removed an extra line from a copy-and-paste error in the display of the cache age. • DRD - 3.0d2 All hexadecimal strings are now prefixed with '$' instead of “0x”. • Drvr - 3.0.2 Changed the storage field to display the “storage” for 68K drivers and the driver version for native drivers (in hex). • EBBE - 2.0b5 Rewrote to use a Time Manager task instead of a VBL task so you can crank down the frequency at which it checks for writes. See the new “-r” (rate) option. We now support the dcmdShutdown message, which allows EBBE to remove its Time Manager task, as well as its Sleep Queue procedure at shutdown time. This is primarily so we don’t bring down the system when MacsBugApp quits. • File - 3.1d2 Changed how we determine if a file belongs to a process to not call the File Manager since it could be busy. • Frags - 1.0b2 We now show the unique closureID when a library is the root of closure. • FSInfo - 3.0 Added support for Foreign File Access file systems. • PageFaults - 1.0b6 Newly public. Fixed parameter parsing so that more than one option can be passed on the command line at a time. Added “-o” (Order) option so that chronological order can be specified (default is reverse-chronological). Added code to listen to the dcmdShutdown message and remove our bus error patch (mainly for MacsBugApp). • ProcInfo - 3.0.2 Made the process name field wider. • Thing Added a “-o” (Open) option that restricts the display to components that are open. • VMDump - 3.0b7 When a page is unmapped, and we’re showing page cacheabilty, we no longer display a garbage string. TEMPLATES AND MACROS AND FRIENDS • Renamed the FCB template FCBRec, and changed it to use real field names from FSM.h. Renamed the WDCB template WDCBRec. Added macros to map FCB to FCBRec and WDCB to WDCBRec. • Added machine names for PowerBookG3Series (Wallstreet), PowerBookG3SeriesFSTN (Mainstreet), and PowerMac4400_160 (who cares?). • Fixed the ID for 6100_66 (should be 100, used to be wrong in Gestalt.h, too). • Added CInfoPB (PBGetCatInfo template), and CInfo, a macro for the same. • Changed MemoryDispatch (A05C) selector to be a byte. • Added InsertFontResMenu and InsertIntlResMenu. • Added Slot Manager templates. • Added PEFSectionHeader and PEFLoaderInfoHeader templates. • Added “drvr -b” to the ShowLog macro. • Added ioWPosOffset.lo to IOParamBlockRec. • Added FileMgrBusy and dmFSQ macros, and changed DoCmdF15 to use dmFSQ. • Bumped the default scrollback history size to 128K. © 1998 Apple Computer, Inc. All rights reserved. Apple, the Apple logo, Apple IIGS, Macintosh, MPW, Power Macintosh, and PowerBook are trademarks of Apple Computer, Inc., registered in the United States and other countries. PowerPC is a trademark of International Business Machines Corporation, used under license therefrom. AltiVec is a trademark of Motorola, Inc.